home *** CD-ROM | disk | FTP | other *** search
/ Aminet 30 / Aminet 30 (1999)(Schatztruhe)[!][Apr 1999].iso / Aminet / util / pack / xpk_Develop.lha / xpk_Develop / Autodocs / xpkmaster.doc next >
Text File  |  1998-11-09  |  34KB  |  909 lines
  1. TABLE OF CONTENTS
  2.  
  3. xpkmaster.library/--general--
  4. xpkmaster.library/XpkAllocObject
  5. xpkmaster.library/XpkClose
  6. xpkmaster.library/XpkExamine
  7. xpkmaster.library/XpkFault
  8. xpkmaster.library/XpkFreeObject
  9. xpkmaster.library/XpkOpen
  10. xpkmaster.library/XpkPack
  11. xpkmaster.library/XpkPassRequest
  12. xpkmaster.library/XpkPrintFault
  13. xpkmaster.library/XpkQuery
  14. xpkmaster.library/XpkRead
  15. xpkmaster.library/XpkSeek
  16. xpkmaster.library/XpkUnpack
  17. xpkmaster.library/XpkWrite
  18. xpkmaster.library/--tags--
  19. xpkmaster.library/--progress--
  20. xpkmaster.library/--data hooks--
  21.  
  22. xpkmaster.library/--general--                   xpkmaster.library/--general--
  23.  
  24.     xpkmaster.library is designed to work under minimum systems. So you may
  25.     use it in games with disabled multitasking as well. It needs access to
  26.     system libraries: utilities.library, exec.library, gadtools.library,
  27.     intuition.library and dos.library. XPK supports locale.library to
  28.     localize internal strings. When locale.library is installed, the first
  29.     access to this library causes an access to ENV: assign, so this assign
  30.     must exist when locale.library is installed.
  31.  
  32. xpkmaster.library/XpkAllocObject             xpkmaster.library/XpkAllocObject
  33.  
  34.     NAME
  35.         XpkAllocObject - Allocate memory for xpk related structures (V4)
  36.  
  37.     SYNOPSIS
  38.         ptr = XpkAllocObject(type, tags)
  39.         D0                    D0    A0
  40.  
  41.         APTR  XpkAllocObject(ULONG , struct TagItem *)
  42.  
  43.         ptr = XpkAllocObjectTags(type, firsttag, ...)
  44.  
  45.         APTR  XpkAllocObjectTags(ULONG, Tag, ...)
  46.  
  47.     FUNCTION
  48.         This function allocates the memory of a needed xpk related
  49.         structure and initializes it. It should help to bring better
  50.         upwards compatibility in next versions. Use it always in newer code.
  51.  
  52.     INPUT
  53.         type    - in xpk/xpk.h defined XPKOBJ_... types.
  54.                   for example XPKOBJ_FIB alloctes XpkFib structure
  55.         tags    - Pointer to an array of struct TagItem. No tags defined
  56.                   at the moment.
  57.  
  58.     RESULT
  59.         ptr     - Pointer to allocated memory of needed size or 0 when an
  60.                   error occured.
  61.  
  62.     SEE ALSO
  63.         xpk/xpk.h, XpkFreeObject()
  64.  
  65. xpkmaster.library/XpkClose                         xpkmaster.library/XpkClose
  66.  
  67.     NAME
  68.         XpkClose - Close an XPK-File
  69.  
  70.     SYNOPSIS
  71.         err = XpkClose(fib)
  72.         D0              A0
  73.  
  74.         LONG  XpkClose(struct XpkFib *)
  75.  
  76.     FUNCTION
  77.         Frees all resources associated with packing or unpacking an
  78.         XPK-File. Note that this may well fail, especially on packing,
  79.         since additional writes have to be made here.
  80.  
  81.     INPUT
  82.         fib     - The Struct XpkFib obtained from XpkOpen()
  83.  
  84.     RESULT
  85.         err     - Global Xpk error code
  86.  
  87.     SEE ALSO
  88.         XpkOpen(), XpkRead(), XpkWrite()
  89.  
  90. xpkmaster.library/XpkExamine                     xpkmaster.library/XpkExamine
  91.  
  92.     NAME
  93.         XpkExamine - Get information about a compressed file
  94.  
  95.     SYNOPSIS
  96.         err = XpkExamine(fib, tags)
  97.         D0                A0   A1
  98.  
  99.         LONG  XpkExamine(struct XpkFib *, struct TagItem *)
  100.  
  101.         err = XpkExamineTags(fib, firsttag, ...)
  102.  
  103.         LONG  XpkExamineTags(struct XpkFib *, Tag, ...)
  104.  
  105.     FUNCTION
  106.         Returns information about compressed data. The output is written
  107.         to the XpkFib structure whose address is passed with the mandatory
  108.         XPK_FileExamine tag. You also have to specify an XPK_In* tag. Note
  109.         that the file position of the in hook will not be altered.
  110.     XPK_GetError is supported.
  111.         A tag field has to end with TAG_DONE.
  112.  
  113.     INPUT
  114.         tags    - Pointer to an array of struct TagItem. You may use 
  115.                   either a XPK_InBuf, a XPK_InName, XPK_InFH or XPK_InHook
  116.                   tag.
  117.  
  118.     RESULT
  119.         err     - Global Xpk error code
  120.  
  121.     SEE ALSO
  122.         xpk/xpk.h
  123.  
  124. xpkmaster.library/XpkFault                         xpkmaster.library/XpkFault
  125.  
  126.     NAME
  127.         XpkFault - Returns the text associated with a Xpk error code (V4)
  128.  
  129.     SYNOPSIS
  130.         len = XpkFault(code, header, buffer, bufsize)
  131.         D0              D0     A0      A1     D1
  132.  
  133.         LONG XpkFault(LONG, STRPTR, STRPTR, LONG)
  134.  
  135.     FUNCTION
  136.         This routine obtains the error message text for the given error code.
  137.         The header is prepended to the text of the error message, followed
  138.         by a colon. Puts a null-terminated string for the error message into
  139.         the buffer. At most len bytes are written to buffer.
  140.  
  141.     INPUTS
  142.         code    - Error code (negative value or 0)
  143.         header  - header to output before error text
  144.         buffer  - Buffer to receive error message.
  145.         bufsize - Length of the buffer.
  146.  
  147.     RESULT
  148.         len     - number of characters put into buffer (may be 0)
  149.  
  150.     SEE ALSO
  151.         XpkPrintFault()
  152.  
  153. xpkmaster.library/XpkFreeObject               xpkmaster.library/XpkFreeObject
  154.  
  155.     NAME
  156.         XpkFreeObject - Frees memory allocated with XpkAllocObject() (V4)
  157.  
  158.     SYNOPSIS
  159.         XpkFreeObject(type, object)
  160.                        D0     A0
  161.  
  162.         void XpkFreeObject(ULONG , APTR)
  163.  
  164.     FUNCTION
  165.         Frees object allocated by XpkAllocObject(). Do not call for objects
  166.         allocated in any other way.
  167.  
  168.     INPUTS
  169.         type    - type passed to XpkAllocObject()
  170.         object  - pointer returned by XpkAllocObject()
  171.  
  172.     SEE ALSO
  173.         xpk/xpk.h, XpkAllocObject()
  174.  
  175. xpkmaster.library/XpkOpen                           xpkmaster.library/XpkOpen
  176.  
  177.     NAME
  178.         XpkOpen - Open a compressed file for partial reading
  179.  
  180.     SYNOPSIS
  181.         err = XpkOpen(fib, tags)
  182.         D0            A0    A1
  183.  
  184.         LONG  XpkOpen(struct XpkFib **, struct TagItem *)
  185.  
  186.     FUNCTION
  187.         Using XpkOpen you can read or write an XPK file without ever having
  188.         all of the file present in RAM. On reading, you cannot pick the 
  189.         size of the chunks. They are given by the file to be decompressed
  190.         and may be up to the whole size of the file.
  191.     XPK_GetError is supported.
  192.     You must supply XPK_NeedSeek, when you wnat to seek in the xpk file.
  193.  
  194.     INPUT
  195.         fib     - Address of a pointer to struct XpkFib
  196.         tags    - Specifying XPK_PackMethod will chose packing mode for
  197.                   this filehandle. Only In-tags are permitted in case
  198.                   of unpacking, and only Out-tags are in case of packing.
  199.                   Anything else will yield undefined results. Progress
  200.                   reports not supported. When packing, you must supply
  201.                   XPK_InLen as well.
  202.  
  203.     RESULT
  204.         fib     - The filehandle. Consists of an XpkFib and some private
  205.                   information. The NLen field in the XpkFib indicates the
  206.                   length of the next chunk.
  207.         err     - Global Xpk error code. If nonzero, no XpkFib was allocated.
  208.  
  209.     SEE ALSO
  210.         XpkRead(), XpkWrite(), XpkClose(), xpkmaster.library/--tags--
  211.  
  212. xpkmaster.library/XpkPack                           xpkmaster.library/XpkPack
  213.  
  214.     NAME
  215.         XpkPack - Compress a data stream
  216.  
  217.     SYNOPSIS
  218.         err = XpkPack(tags)
  219.         D0             A0
  220.  
  221.         LONG  XpkPack(struct TagItem *)
  222.  
  223.         err = XpkPackTags(firsttag, ...)
  224.  
  225.         LONG  XpkPackTags(Tag, ...)
  226.  
  227.     FUNCTION
  228.         Compresses a file or a memory area to a different file or memory
  229.         area. You need to specify at least one XPK_In... tag, at least
  230.         one XPK_Out... tag, plus XPK_PackMethod.
  231.     XPK_GetError is supported.
  232.         A tag field has to end with TAG_DONE.
  233.  
  234.     INPUT
  235.         tags    - Pointer to an array of struct TagItem.
  236.  
  237.     RESULT
  238.         err     - Global Xpk error code.
  239.  
  240.     SEE ALSO
  241.         xpkmaster.library/--tags--, xpk/xpk.h
  242.  
  243. xpkmaster.library/XpkPassRequest             xpkmaster.library/XpkPassRequest
  244.  
  245.     NAME
  246.         XpkPassRequest - opens a password Requester (V4)
  247.  
  248.     SYNOPSIS
  249.         err = XpkPassRequest(tags)
  250.         D0                    A0
  251.  
  252.         LONG  XpkPassRequest(struct TagItem *)
  253.  
  254.         err = XpkPassRequestTags(firsttag, ...)
  255.  
  256.         LONG  XpkPassRequestTags(Tag, ...)
  257.  
  258.     FUNCTION
  259.         Opens a requester to ask the user for a password. The requester
  260.         can ask for a password or a 16/32 bit key. It has a tunable
  261.         timeout to allow batch work.
  262.  
  263.     This function needs at least 2 free signal bits for message ports.
  264.  
  265.     INPUT
  266.         tags    - Pointer to an array of struct TagItem.
  267.                   Either XPK_Preferences or one of the following:
  268.  
  269.     TAGS
  270.         XPK_PassChars   (ULONG)
  271.            Tell the requester which characters are allowed in the password.
  272.            Use XPKPASSFLG_... and XPKPASSFF_... defines.
  273.  
  274.         XPK_PasswordBuf (STRPTR)
  275.            Pointer to memory area, where the password should be stored.
  276.            Requires XPK_PassBuffSize tag.
  277.  
  278.         XPK_PassBufSize (ULONG)
  279.            Size of the buffer passed with XPK_PasswordBuf.
  280.  
  281.         XPK_Key16BitPtr (UWORD *)
  282.            Ask for an 16 bit key instead of a password. Data is a pointer
  283.            to a 16 bit (UWORD) variable. XPK_PassChars is ignored here, as
  284.            input is always hexadecimal.
  285.  
  286.         XPK_Key32BitPtr (ULONG *)
  287.            Ask for an 32 bit key. Data points to a 32 bit (ULONG) variable.
  288.        XPK_PassChars is ignored here, as input is always hexadecimal.
  289.  
  290.         XPK_PubScreen (struct Screen *)
  291.            Pointer of type struct Screen of the public screen, the
  292.            requester should open on. If not given, the requester opens on
  293.            default public screen. The screen must by locked by use of
  294.            LockPubScreen or garanted not to be closed during request!
  295.  
  296.         XPK_PassTitle (STRPTR)
  297.            Is the text, which is shown in the title line of the window. If
  298.            not given, the internal defaults are used.
  299.  
  300.         XPK_TimeOut (ULONG)
  301.            Time after which the requester should close automatically, when
  302.            no user action happend. 0 means no timeout.
  303.  
  304.     XPK_PassVerify (BOOL) (V4 REV25)
  305.        When this tag is specified, the user needs to enter the password
  306.        or passkey twice for verification. This option should be used
  307.        when password is needed for packing.
  308.  
  309.     XPK_PassWinLeft (UWORD) (V4 REV25)
  310.        This specifies the distance from left screen border to left
  311.        border of password requester. When not given, the window is
  312.        centered on screen.
  313.  
  314.     XPK_PassWinTop (UWORD) (V4 REV25)
  315.        This specifies the distance from top screen border to top
  316.        border of password requester. When not given, the window is
  317.        centered on screen.
  318.  
  319.     XPK_PassWinWidth (UWORD) (V4 REV25)
  320.        This specifies the width of the password requester. It must be
  321.        large enough (50 + borders) or the internal defaults are used.
  322.  
  323.     XPK_PassWinHeight (UWORD) (V4 REV25)
  324.        This specifies the height of the password requester. It must be
  325.        large enough (inner height a bit larger than font height) or the
  326.        internal defaults are used.
  327.  
  328.     XPK_PassCenter (BOOL) (V4 REV25)
  329.        When this is given, the above XPK_PassWinLeft and XPK_PassWinTop
  330.        are are interpreted as the center of the requester and not as
  331.        its upper left edge.
  332.  
  333.     RESULT
  334.         err     - Global Xpk error code.
  335.  
  336.     SEE ALSO
  337.         xpk/xpk.h
  338.  
  339. xpkmaster.library/XpkPrintFault               xpkmaster.library/XpkPrintFault
  340.  
  341.     NAME
  342.         XpkPrintFault - Prints the text associated with a Xpk error code (V4)
  343.  
  344.     SYNOPSIS
  345.         success = XpkPrintFault(code, header)
  346.         D0                       D0     A0
  347.  
  348.         BOOL XpkPrintFault(LONG, STRPTR)
  349.  
  350.     FUNCTION
  351.         This routine obtains and prints the error message text for the
  352.         given error code. This is similar to the XpkFault() function,
  353.         except that the output is written to the default output
  354.         channel with buffered output.
  355.  
  356.     INPUTS
  357.         code    - Error code (negative value or 0)
  358.         header  - header to output before error text
  359.  
  360.     RESULT
  361.         success - Success/failure code. Return of 0 means failure.
  362.  
  363.     SEE ALSO
  364.         XpkFault()
  365.  
  366. xpkmaster.library/XpkQuery                         xpkmaster.library/XpkQuery
  367.  
  368.     NAME
  369.         XpkQuery - Gain information about packers
  370.  
  371.     SYNOPSIS
  372.         err = XpkQuery(tags)
  373.         D0              A0
  374.  
  375.         LONG  XpkQuery(struct TagItem *)
  376.  
  377.         err = XpkQueryTags(firsttag, ...)
  378.  
  379.         LONG  XpkQueryTags(Tag, ... )
  380.  
  381.     FUNCTION
  382.         Finds out a list of available packers or various parameters of a
  383.         packer. When using the tag XPK_PackersQuery, you must supply a
  384.         XpkPackerList structure and will receive a list of available
  385.         packers. The second possibility, XPK_PackerQuery, expects a
  386.         pointer to a XpkPackerInfo structure which will be filled in with
  387.         information about a packer, and XPK_ModeQuery fills in a XpkMode
  388.         structure with information about some mode (or the default mode)
  389.         of a packer. XPK_PackMethod must be present when using the latter
  390.         two queries, and XPK_PackMode can be for ModeQuery.
  391.     XPK_GetError is supported. Every call only one query is allowed!
  392.  
  393.     The flag XPKIF_MODES does not mean, the library supports different
  394.     mode settings (as ALL libraries do that), but means there are
  395.     different XpkMode structures! So when XPKIF_MODES is not set, the
  396.     user still needs to be able to select all 100 modes!
  397.  
  398.     Pass {XPK_Preferences, FALSE} as tags to disable the dummy packer
  399.     USER, which implements the preferences packing. Then handle the
  400.     preferences mode internally, as the statistics passed with
  401.     XPK_ModeQuery and XPK_PackerQuery are not very useful.
  402.  
  403.     RESULT
  404.         err     - Global Xpk error code.
  405.  
  406.     SEE ALSO
  407.         xpk/xpk.h
  408.  
  409. xpkmaster.library/XpkRead                           xpkmaster.library/XpkRead
  410.  
  411.     NAME
  412.         XpkRead - Unpack one part of an XPK-File
  413.  
  414.     SYNOPSIS
  415.         read = XpkRead(fib, buf, len )
  416.         D0              A0   A1   D0
  417.  
  418.         LONG  XpkRead(struct XpkFib *, UBYTE *, LONG)
  419.  
  420.     FUNCTION
  421.         Reads one chunk from an XPK-file and decompresses it to the
  422.         memory area indicated.
  423.  
  424.     INPUT
  425.         fib     - The XpkFib obtained from XpkOpen(). It must be a read-
  426.                   handle, ie. there was no XPK_PackMethod tag among the
  427.                   tags passed to XpkOpen().
  428.         buf     - The memory area to write the destination to
  429.         len     - The number uncompressed bytes to output. Note that you
  430.                   cannot choose these freely but must take them from 
  431.                   the xf_NLen field in the XpkFib.
  432.  
  433.     RESULT
  434.         read    - The number of bytes read. 0 indicates EOF, negative
  435.                   numbers are global error codes. Long error messages 
  436.                   written to buffer passed through XPK_GetError in 
  437.                   XpkOpen(). This number of bytes read will usually be
  438.                   smaller than the number requested!
  439.  
  440.     SEE ALSO
  441.         XpkOpen(), XpkWrite(), XpkClose(), examples/
  442.  
  443. xpkmaster.library/XpkSeek                           xpkmaster.library/XpkSeek
  444.  
  445.     NAME
  446.         XpkSeek - Seek in an compressed file (V5)
  447.  
  448.     SYNOPSIS
  449.         res = XpkSeek(fib, dist, mode)
  450.         D0            A0    D0      D1
  451.  
  452.     LONG  XpkSeek(struct XpkFib *, LONG, LONG);
  453.  
  454.     FUNCTION
  455.     This functions seeks in xpk compressed files! It can be used, when
  456.     the file is manually handled using XpkOpen and XpkRead. You need
  457.     to use XPK_NeedSeek flag on XpkOpen to turn seekability on.
  458.     Like normal DOS function Seek(), you seek into an file by
  459.     specifying an offset and the mode (BEGINNING, CURRENT, END).
  460.     
  461.     Unlike DOS Seek() function the result is not the file position, but
  462.     an global error code and the file position DOES NOT MATCH the
  463.     wanted position. The XpkSeek() function always seeks to the start
  464.     of the chunk, which contains the wanted position! If the return
  465.     value is positive, the offset from chunk start is returned.
  466.  
  467.     An example: There is an file with chunksize 512 bytes and you
  468.     already read 2 chunks (xfib->xf_UCur is 1024). You call XpkSeek
  469.     with XPKSEEK_CURRENT and +3: The seek is done with 0 bytes, as you
  470.     are already at that position, but return value is 3.
  471.     XPKSEEK_CURRENT and -3 brings you to the chunk before
  472.     (xfib->xf_UCur is 512) and return value is 509.
  473.     Note that the chunks need not to have equal length!
  474.  
  475.     A call to XpkSeek corrects the entries in XpkFib.
  476.  
  477.     The Seek function works for unpacked and xpk packed input streams.
  478.     XFD crunched data is not supported (as this is really useless).
  479.  
  480.     As The XPKIF_NOSEEK flag is new for V5, not all libraries may
  481.     have it and thus there may be libraries not supporting seeking
  482.     without that flag.
  483.  
  484.     INPUT
  485.         fib     - The XpkFib obtained from XpkOpen(). It must be a read-
  486.                   handle, ie. there was no XPK_PackMethod tag among the
  487.                   tags passed to XpkOpen().
  488.         dist    - The positive a negative distance to seek in uncompressed
  489.           data stream.
  490.         mode    - Either
  491.               XPKSEEK_BEGINNING, when dist is an offset from file start,
  492.               XPKSEEK_END, when dist is an offset from file end or
  493.               XPKSEEK_CURRENT, when dist is an offset to current pos.
  494.  
  495.     RESULT
  496.         res    - Global XPK error code (<0) or seek offset addition
  497.  
  498.     SEE ALSO
  499.         XpkOpen(), XpkRead(), xpkmaster.library/--tags--, xpk/xpk.h
  500.  
  501. xpkmaster.library/XpkUnpack                       xpkmaster.library/XpkUnpack
  502.  
  503.     NAME
  504.         XpkUnpack - Decompress a data stream
  505.  
  506.     SYNOPSIS
  507.         err = XpkUnpack(tags)
  508.         D0             A0
  509.  
  510.         LONG  XpkUnpack(struct TagItem *)
  511.  
  512.         err = XpkUnpackTags(firsttag, ...)
  513.  
  514.         LONG  XpkUnpackTags(Tag, ...)
  515.  
  516.     FUNCTION
  517.         Decompresses a file or a memory area to a different file or memory
  518.         area. You need to specify at least one XPK_In... tag, at least
  519.         one XPK_Out... tag. A tag field has to end with TAG_DONE.
  520.     XPK_GetError is supported.
  521.  
  522.     INPUT
  523.         tags   - Pointer to an array of struct TagItem.
  524.  
  525.     RESULT
  526.         err    - Global Xpk error code.
  527.  
  528.     SEE ALSO
  529.         xpkmaster.library/--tags--
  530.  
  531. xpkmaster.library/XpkWrite                         xpkmaster.library/XpkWrite
  532.  
  533.     NAME
  534.         XpkWrite - Pack one part of an XPK-File
  535.  
  536.     SYNOPSIS
  537.         err = XpkWrite(fib, buf, len)
  538.         D0              A0   A1   D0
  539.  
  540.         LONG  XpkWrite(struct XpkFib *, UBYTE *, LONG)
  541.  
  542.     FUNCTION
  543.         Compresses the memory area indicated and writes it to an
  544.         XPK-File.
  545.  
  546.     INPUT
  547.         fib     - The XpkFib obtained from XpkOpen(). Must be a write-
  548.                   handle, ie. XPK_PackMethod must have been among the
  549.                   tags passed to XpkOpen().
  550.         buf     - The memory area to compress
  551.         len     - The number bytes to compress. Note you may not choose
  552.                   them freely, you must always deliver as many bytes
  553.                   as the NLen field of the XpkFib indicates. You may try
  554.                   to influence it by passing XPK_ChunkLen to XpkOpen().
  555.                   Important: The first chunk written *must* be the
  556.                   biggest!
  557.  
  558.     RESULT
  559.         err    - global error codes. Error messages are written to
  560.               buffer passed through XPK_GetError in XpkOpen().
  561.  
  562.     SEE ALSO
  563.         XpkOpen(), XpkRead(), XpkClose(), examples/
  564.  
  565. xpkmaster.library/--tags--                         xpkmaster.library/--tags--
  566.  
  567.     THE TAGS FOR XpkPack() AND XpkUnpack()
  568.  
  569.     THE INPUT TAGS. One of the four must be present.
  570.  
  571.         XPK_InName (STRPTR)
  572.             Name of file to (de)compress. On packing, XPK_InLen can be 
  573.             specified in order to pack only the first N bytes. On de-
  574.             compression, only one file will be decompressed, even if 
  575.             there is additional data at the end.
  576.  
  577.         XPK_InFH (BPTR)
  578.             File handle to (de)compress from. It is not necessary that
  579.             the handle is at the beginning of the file. Otherwise same
  580.             rules as in XPK_InName apply.
  581.  
  582.         XPK_InBuf (APTR)
  583.             Memory block to (de)compress. If you use this one, you 
  584.             have to specify InLen as well.
  585.  
  586.         XPK_InHook (struct Hook *)
  587.             Hookfunc to deliver data for (de)compression. See special
  588.             chapter on I/O hook functions. Must also supply XPK_InLen,
  589.             else the hook itself is asked for input filelength.
  590.  
  591.     IN ADDITION
  592.  
  593.         XPK_InLen (LONG)
  594.             Specifies the number of bytes to read when compressing.
  595.             ignored on decompression of normal xpk files. It should be
  596.             supplied for decompression to allow decrunching of non xpk
  597.             files.
  598.  
  599.     THE OUTPUT TAGS. One of the five must be present.
  600.  
  601.         XPK_OutName (STRPTR)
  602.             Name of file write (de)compressed data to.
  603.  
  604.         XPK_OutFH (BPTR)
  605.             File handle to append (de)compressed data to. This filehandle
  606.             must be writable, so MODE_OLDFILE filehandles may fail, as
  607.             these open a file in shared mode.
  608.  
  609.         XPK_OutBuf (APTR)
  610.             The memory block to write (de)compressed data to. Must also
  611.             supply XPK_OutBufLen. On packing, its size must be at least
  612.             inlen+inlen/32+2*XPK_MARGIN. On unpacking, it needs only be
  613.             outlen+XPK_MARGIN. Use XpkExamine() to find out outlen. Note
  614.             that this buffer must be word aligned.
  615.  
  616.         XPK_GetOutBuf (APTR *)
  617.             Allocates a block of appropriate size and stores a pointer to
  618.             it in the variable pointed to by ti_Data. Must also supply 
  619.             XPK_GetOutBufLen plus XPK_GetOutLen and can XPK_OutMemType.
  620.  
  621.         XPK_OutHook (struct Hook *)
  622.             Hookfunc to accept (de)compressed data. See special chapter
  623.             on I/O hook functions.
  624.  
  625.     IN ADDITION
  626.  
  627.         XPK_OutBufLen (LONG)
  628.             The length of the output buffer you supply using XPK_OutBuf.
  629.             For decompression, must be decompressed size (see XpkExamine())
  630.             plus XPK_MARGIN. For compression, inlen+inlen/32+2*XPK_MARGIN.
  631.  
  632.         XPK_GetOutLen (LONG *)
  633.             Stores the total length of the (de)compressed data in the
  634.             variable pointed to by ti_Data.
  635.  
  636.         XPK_GetOutBufLen (LONG *)
  637.             Stores the length of the buffer allocated for the data in the
  638.             variable pointed to by ti_Data. FreeMem() the buffer you get
  639.             from XPK_GetOutBuf with the length you get from XPK_GetOutBufLen.
  640.             Note: For the number of bytes written, refer to XPK_GetOutLen!
  641.  
  642.         XPK_OutMemType (LONG)
  643.             The type of memory to use for the output buffer.
  644.  
  645.     You have to specify different input and output streams always. So it
  646.     produces wrong results, when you supply same buffer for XPK_InBuf and
  647.     XPK_OutBuf or same filehandle for XPK_InFH and XPK_OutFH.
  648.     
  649.     PACKING TAGS
  650.  
  651.         XPK_PackMethod (STRPTR)
  652.             Use indicated method for packing. This would be a four
  653.             letter string of uppercase characters and numbers.
  654.  
  655.         XPK_PackMode (LONG)
  656.             Packing mode for sublib to use. Range is 0...100, where 100 is
  657.             most efficient.
  658.  
  659.         XPK_StepDown (BOOL)
  660.             Reduce packing efficiency to save mem if necessary.
  661.  
  662.         XPK_ChunkSize (LONG)
  663.             Chunk size to try to pack with. May be altered by the
  664.             master library.
  665.  
  666.     XPK_LossyOK (BOOL)
  667.         Some packers, like MPEG, reduce the file size by deleting some
  668.         information. These information cannot be restored. This tag
  669.         tells xpkmaster.library if it is ok for you, that some
  670.         information is deleted. It is FALSE by default. Use it with
  671.         care! Should be used only with sound or picture files.
  672.  
  673.     QUERY TAGS
  674.  
  675.         XPK_PackersQuery (struct XpkPackerList *)
  676.             Returns an array of available packers names in the XpkPackerList
  677.             structure whose address is stored in the ti_Data field of this
  678.             tag.
  679.  
  680.         XPK_PackerQuery (struct XpkPackerInfo *)
  681.             Returns information about one single packer in the XpkPackerInfo
  682.             structure whose address is stored in the ti_Data field of this
  683.             tag. See xpk/xpk.h for the meaning of the fields therein. You
  684.             must also supply XPK_PackMode.
  685.  
  686.         XPK_ModeQuery (struct XpkMode *)
  687.             Returns information about one single packer mode in the XpkMode
  688.             structure whose address is stored in the ti_Data field of this
  689.             tag. See xpk/xpk.h for the meaning of the fields therein. The
  690.             data of xm_Next field is illegal and must not be used. You
  691.             must also supply XPK_PackMethod and optionally XPK_PackMode,
  692.             otherwise the default mode will be used.
  693.  
  694.     OTHER TAGS
  695.  
  696.         XPK_GetError (STRPTR)
  697.             Write error msg to the buffer passed. The buffer must be of 
  698.             size XPKERRMSGSIZE. This tag calls XpkFault internally.
  699.             It is not recommended to use this tag any longer.
  700.  
  701.         XPK_Password (STRPTR)
  702.             Use password for en- or decoding. Passing a NULL pointer or
  703.             zero length string is equivalent to omitting this tag.
  704.  
  705.     XPK_Key16 (UWORD) (V4 REV25)
  706.         Supply a 16 bit key for decrunching of encrypted data. This
  707.         is only for decrunching of alien formats. XPK does not support
  708.         crunching with keys. Only know usage: crypted RNC files.
  709.  
  710.     XPK_Key32 (ULONG) (V4 REV25)
  711.         Supply a 32 bit key for decrunching of encrypted data. This
  712.         is only for decrunching of alien formats. XPK does not support
  713.         crunching with keys. Currently no know usage.
  714.  
  715.         XPK_ChunkHook (struct Hook *)
  716.             Hook function to call between chunks. Can print a progress
  717.             report, and if it returns a nonzero value, the (de)compression
  718.             will be aborted. See special chapter on chunk functions.
  719.  
  720.         XPK_PassThru (BOOL)
  721.             If true, data will just be handed trough on decompression if they
  722.             were not packed. Otherwise you get XPKERR_NOTPACKED.
  723.  
  724.         XPK_TaskPri (UBYTE)
  725.             The task priority to use during the (de)crunching. Use -1 for
  726.             background decompression.
  727.  
  728.         XPK_FileName (STRPTR)
  729.             The name to print in the progress report. If none is given, the
  730.             InName will be used when packing and the OutName when unpacking.
  731.  
  732.     XPK_NeedSeek (BOOL) (V5)
  733.         If true (in XpkOpen), the XpkSeek function can be used.
  734.  
  735.     PREFERENCES RELATED TAGS
  736.  
  737.         XPK_UseXfdMaster (BOOL) (V4)
  738.             If TRUE, xfdmaster.library will be used for checking unknown
  739.             files. Useable with XpkUnpack() and XpkExamine(). Is FALSE by
  740.             default, but depends on preference settings.
  741.  
  742.         XPK_UseExternals (BOOL) (V4)
  743.             If TRUE, xex libraries in LIBS:compressors/extern will be used
  744.             to check for crunched files. Useable with XpkUnpack() and
  745.             XpkExamine(). Default value is TRUE (depends on prefs!)
  746.  
  747.         XPK_PassRequest (BOOL) (V4)
  748.             If this is set a requester will be used to query the user for a
  749.             password, if none is given. Useable with XpkPack(). This is
  750.             disabled by default, but can be overridden using preferences
  751.             settings.
  752.  
  753.         XPK_Preferences (BOOL) (V4)
  754.             Tell xpkmaster.library whether to use its preferences system,
  755.             or not. This is enabled by default.
  756.  
  757.     XPK_ChunkReport (BOOL) (V4)
  758.         If this tag is set, xpkmaster.library brings an automatic chunk
  759.         report request (when the preferences semaphore has a valid
  760.         function for that). This is disabled by default.
  761.  
  762. xpkmaster.library/--progress--                 xpkmaster.library/--progress--
  763.  
  764.     THE PROGRESS REPORT HOOK
  765.         The progress report function is a standard hook function that will
  766.         be called after every chunk (de)compressed. This will be about 
  767.         every 30K, or just twice if the file format is not split in chunks.
  768.         If the field h_Entry in the hook is set, it will be called with 
  769.         the hook itself in A0 and the progress report structure in A1.
  770.         If the progress report function returns a nonzero value,
  771.         (de)compression aborts.
  772.         NOTE: Because hooks are not called in program environment, they
  773.         cannot be used in small data model of some compilers, as register
  774.         A4 is not passed through. So the hook either has to be compiled in
  775.         large data model or should use __saveds keyword of some compilers.
  776.  
  777. xpkmaster.library/--data hooks--             xpkmaster.library/--data hooks--
  778.  
  779.     GENERAL
  780.     You have four methods of passing data to xpkmaster.library: file-
  781.     names, filehandles, memory areas and hooks. The hooks are described
  782.     here. The hook field h_Entry has to be standard hook functions and
  783.     gets called with the hook itself in A0 and a pointer to a XpkIOMsg
  784.     in A1. Commands are stored in xiom_Type field, data in the other
  785.     fields. Return values are 0 or any of the XPKERR codes.
  786.     Commands XIO_FREE and XIO_ABORT may be ignored.
  787.  
  788.     Whenever an error occurs, you have to return an XPKERR code and
  789.     stop work. You get a XIO_ABORT call in this case later. When no
  790.     error occured, return 0.
  791.  
  792.     You may store private data in the free fields of XpkIOMsg structure.
  793.     You are always called with XIO_FREE or XIO_ABORT, so you can free
  794.     private stuff there. Buffers can be freed, when next time a buffer
  795.     allocation is required.
  796.  
  797.         NOTE: Because hooks are not called in program environment, they
  798.         cannot be used in small data model of some compilers, as register
  799.         A4 is not passed through. So the hook either has to be compiled in
  800.         large data model or should use __saveds keyword of some compilers.
  801.  
  802.     BUFFERS
  803.     Your hooks must be able to allocate buffers for read/write or pass
  804.     pointers to them, when they are already allocated. There are some
  805.     ways you have to handle this. First there is XIO_GETBUF. When getting
  806.     this command you have to pass a memory pointer pointing to a region
  807.     of at least xmm_Size size. For in hook there is another additionally
  808.     method. When XIO_READ is wanted and xiom_Ptr is zero, then you have
  809.     to pass (and allocate) a buf pointer and to fill it!
  810.     
  811.     The buffers must be valid until you are next time asked to allocate
  812.     a buffer (either with XIO_GETBUF or XIO_READ). Then you may return
  813.     old buffer pointer (when memory is large enough) or allocate a new
  814.     buffer and free the old buffer. When XIO_ABORT or XIO_FREE is send
  815.     all your buffers should be freed.
  816.  
  817.     NOTE: Your hooks do not get called only with your own buffers, but
  818.     also with xpkmaster internally buffers!
  819.  
  820.     When your input data is already in memory, you may pass pointers
  821.     to your memory regions and need not to allocate new memory for
  822.     XIO_READ when pointer is zero. When xiom_Ptr is not zero for
  823.     XIO_READ, you have to copy the data.
  824.  
  825.     Never expect, that you are called next time with buffer you
  826.     allocated. There may be write cycles of headers and other stuff
  827.     between XIO_GETBUF and XIO_WRITE. On reading it is equal.
  828.  
  829.     COMMANDS
  830.     XIO_READ    (in hooks only)
  831.       This command is called all time xpkmaster.library needs some data.
  832.       You have to fill the supplied memory area with input data of
  833.       needed size (not more!) When the input memory pointer is zero,
  834.       you have to allocate your own buffer and fill it. When you
  835.       allocated a buffer before (either by XIO_GETBUF or XIO_READ) you
  836.       can free it when pointer is zero.
  837.       Input:    xiom_Size    size of required data
  838.               xiom_Ptr    already allocated buffer or zero
  839.       Output:    xiom_Ptr    pointer to memory area of xiom_Size
  840.  
  841.     XIO_WRITE    (out hooks only)
  842.       This function is called, when some data was compressed and should
  843.       be stored now. Copy the contents of buffer to your data storing
  844.       system.
  845.       Input:    xiom_Size    size of data
  846.               xiom_Ptr    pointer to memory area of xiom_Size
  847.       Output:    none
  848.  
  849.     XIO_FREE    (both)
  850.       You get this when work is finished, free all your stuff now.
  851.       Input:    none
  852.       Output:    none
  853.  
  854.     XIO_ABORT    (both)
  855.       You get this when work was aborted, because an error occured.
  856.       Free all your stuff now.
  857.       Input:    none
  858.       Output:    none
  859.  
  860.     XIO_GETBUF    (both)
  861.       Asks you to pass a needed buffer. This buffer is not freed by
  862.       xpkmaster.library. Do this when getting XIO_FREE, XIO_ABORT or
  863.       the next XIO_GETBUF. Input buffers may be freed too, when
  864.       XIO_READ is called with no pointer.
  865.       Input:    xiom_Size    size of necessary buffer
  866.       Output:    xiom_Ptr    pointer to the buffer
  867.  
  868.     XIO_SEEK    (both)
  869.       Change the current position in your data (like dos.library Seek
  870.       command). When you are not able to handle seek, all better
  871.       functions will fail. Pass XPKERR_NOFUNC in this case as return
  872.       value. The offset you have to seek is always relative to current
  873.       position. It can be negative too. Return value (xiom_Size) is
  874.       same as for dos.library Seek command.
  875.       Input:    xiom_Size    offset you have to seek
  876.       Output:    xiom_Size    buffer position before seek
  877.  
  878.     XIO_TOTSIZE    (both)
  879.       You either have to tell the total input data size (in hook) or get
  880.       told the total output data size (out hook).
  881.  
  882.       OUT HOOK:
  883.       XIO_TOTSIZE may be ignored here. It tells you the maximum size
  884.       of output file (the real size may be shorter). This is for
  885.       example needed in memory hooks. This is only to inform you.
  886.       This command never needs to return an error code.
  887.       Input:    xiom_Size    total size of output data
  888.       Output:    none
  889.  
  890.       IN HOOK:
  891.       XIO_TOTSIZE cannot be ignored here. When your hook cannot
  892.       determine the total filesize, return any of the XPKERR values.
  893.       XIO_TOTSIZE is called only, when xpkmaster library really needs
  894.       filesize. Normal XPK files have size information in header and
  895.       XPK_InLen flags supplies information for input. In these cases
  896.       XIO_TOTSIZE is not used. But when returning an XPKERR, your hook
  897.       will not work in other cases, when size is required.
  898.       XIO_TOSIZE is used for following cases (when no XPK_InLen is
  899.       supplied!):
  900.       - decrunching of all non-xpk files
  901.       - crunching of files
  902.       NOTE: Only the size of the part, which should be processed, is
  903.       wanted. Most time this is from current position to end of file
  904.       (memory), but it may be shorter. But generally you have to
  905.       calculate size starting at current position.
  906.       Input:    none
  907.       Output:    xiom_Size    total size of input data
  908.  
  909.